feat: add JSON schemas and Copilot prompts for filter/override configuration#183
Merged
Merged
Conversation
…uration
- Add auto-generated JSON Schema files (schemas/extractor-config.schema.json,
schemas/override-config.schema.json) for IDE autocompletion in YAML configs
- Add scripts/generate-schemas.mjs that derives schemas from TypeScript
interfaces and runs on every build/lint/test
- Add Copilot prompt files (apiops-configure-filter, apiops-configure-overrides)
that conversationally guide users through creating filter and override files
- Update apiops init to lay down the new prompt files alongside identity setup
- Include {#[TOKEN_NAME]#} placeholder syntax guidance and Key Vault patterns
in the overrides prompt (per issue #117)
- Update docs for filtering-resources, environment-overrides, and init command
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
EMaher
commented
Jun 23, 2026
Contributor
Author
|
@copilot, have the Squad handle all the comments in this PR. |
…tect instead The overrides prompt now instructs Copilot to detect environments by scanning for existing configuration.*.yaml files before falling back to asking the user. This makes the prompt reusable outside of apiops init context. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Move the shared renderTemplate function from src/templates/shared/template-utils.ts to src/lib/render-template.ts and remove the duplicate private method from identity-guide-service.ts. All template consumers now import from the single canonical location. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves authoring ergonomics for APIOps filter (configuration.extractor.yaml) and override (configuration.{env}.yaml) configs by adding IDE JSON Schemas (published under schemas/v1/) and adding new GitHub Copilot “prompt” templates that apiops init scaffolds into .github/prompts/.
Changes:
- Add schema generation (
scripts/generate-schemas.mjs) and commit the generated schemas underschemas/v1/for editor autocomplete/validation. - Add Copilot prompt templates for configuring filters and environment overrides, and have
apiops initgenerate them. - Update config templates to include
yaml-language-server$schemaheaders, update packaging tests to include YAML templates, and refresh docs/devcontainer tooling.
Reviewed changes
Copilot reviewed 30 out of 30 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/unit/templates/copilot/configure-overrides-prompt.test.ts | Adds unit coverage for the overrides Copilot prompt generator. |
| tests/unit/templates/copilot/configure-filter-prompt.test.ts | Adds unit coverage for the filter Copilot prompt generator. |
| tests/unit/templates/configs/config-templates.test.ts | Verifies generated config templates include schema URLs and no unrendered placeholders. |
| tests/unit/services/init-service.test.ts | Extends init-service tests to cover prompt generation and conflict detection. |
| tests/integration/package-build/package-build.test.ts | Updates packaging test to assert YAML templates are embedded/shipped, not only markdown. |
| src/templates/copilot/identity-setup-prompt.ts | Refactors to reuse shared renderTemplate helper. |
| src/templates/copilot/configure-overrides-prompt.ts | Adds generator for the overrides Copilot prompt template (static content). |
| src/templates/copilot/configure-overrides-prompt.md | Adds the overrides Copilot prompt content to guide creating configuration.{environment}.yaml files. |
| src/templates/copilot/configure-filter-prompt.ts | Adds generator for the filter Copilot prompt template (currently static). |
| src/templates/copilot/configure-filter-prompt.md | Adds the filter Copilot prompt content to guide creating configuration.extractor.yaml. |
| src/templates/configs/schema-ref.ts | Adds helper to build versioned raw GitHub schema URLs from package.json’s schemaVersion. |
| src/templates/configs/override-config.yaml | Adds an override config template with a $schema placeholder for init-time rendering. |
| src/templates/configs/override-config.ts | Switches override config generation to embedded template + token rendering + schema URL injection. |
| src/templates/configs/filter-config.yaml | Adds a filter config template with a $schema placeholder for init-time rendering. |
| src/templates/configs/filter-config.ts | Switches filter config generation to embedded template + token rendering + schema URL injection. |
| src/services/init-service.ts | Adds generation + conflict detection for the two new Copilot prompt files during init. |
| src/services/identity-guide-service.ts | Refactors to reuse shared renderTemplate helper. |
| src/lib/render-template.ts | Introduces shared {{TOKEN}} template rendering utility. |
| scripts/generate-schemas.mjs | Adds schema generator deriving schema structure from config model field names and emitting to schemas/v<N>/. |
| scripts/embed-markdown-templates.mjs | Embeds the new Copilot prompts and the new YAML config templates into generated constants. |
| schemas/v1/override-config.schema.json | Adds the published JSON Schema for override files. |
| schemas/v1/extractor-config.schema.json | Adds the published JSON Schema for extractor filter files. |
| package.json | Adds schemaVersion and runs schema generation in prelint/prebuild/pretest. |
| docs/guides/filtering-resources.md | Documents $schema usage and points to the init-generated Copilot prompt. |
| docs/guides/environment-overrides.md | Documents $schema usage and points to the init-generated Copilot prompt (contains a duplicated schema section). |
| docs/commands/init.md | Documents new prompt files and updates “next steps” guidance to mention them. |
| .github/skills/update-config-schema-version/SKILL.md | Adds internal skill documentation for safely bumping schema versions and updating references. |
| .github/skills/codespace-multi-repo/SKILL.md | Adds internal skill documentation for multi-repo auth workflows in Codespaces/devcontainers. |
| .github/skills/codespace-clone-repo/SKILL.md | Removes the old single-repo clone skill doc (replaced by the multi-repo skill). |
| .devcontainer/devcontainer.json | Adds the Red Hat YAML extension to support schema-based autocomplete in the devcontainer. |
petehauge
approved these changes
Jun 25, 2026
petehauge
left a comment
petehauge
left a comment
Collaborator
There was a problem hiding this comment.
Marking approve since I think all my suggestions can be done later if needed!
9 tasks
Copilot AI
added a commit
that referenced
this pull request
Jun 29, 2026
…d docs - Add links to prompt template source files for users who skipped `apiops init` in docs/guides/environment-overrides.md and docs/guides/filtering-resources.md - Remove artificial word wrapping from configure-filter-prompt.md and configure-overrides-prompt.md (let editors handle text wrap) - configure-overrides-prompt.md Step 3: inspect pipeline files first to discover existing variables before asking the user - configure-overrides-prompt.md Step 3: run `gh --version` and offer to auto-query `gh variable list`/`gh secret list` (names only) with permission - configure-overrides-prompt.md Step 3: validate user-provided token names against discovered pipeline variables (warn on mismatch) - configure-overrides-prompt.md Step 5: structural YAML schema validation (top-level keys, name+properties shape, obvious misspellings) - configure-overrides-prompt.md Step 5: replace vague "show" with ask-user- to-review-before-checking-in instruction - Prompt naming (apiops- prefix) already implemented; no change needed Closes #195
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
When working with
configuration.extractor.yaml(filter) andconfiguration.{env}.yaml(override) files, users have no IDE autocompletion or guided workflow for building these configs correctly. This makes onboarding harder and increases the chance of typos or structural mistakes.Approach
This PR adds two complementary features:
JSON Schema files (
schemas/extractor-config.schema.json,schemas/override-config.schema.json) that provide IDE autocompletion via theyaml-language-server$schemadirective. These are auto-generated from the TypeScript interfaces on every build by a newscripts/generate-schemas.mjsscript, so they stay in sync with the code automatically.Copilot prompt files (
apiops-configure-filter.prompt.md,apiops-configure-overrides.prompt.md) that conversationally guide users through creating filter/override files. The overrides prompt covers environment promotion (dev -> stage -> prod), Key Vault references, and{#[TOKEN_NAME]#}pipeline placeholder syntax per Enable pipeline token/placeholder substitution in publish pipeline (APIOps Toolkit parity) #117.Both prompts are laid down by
apiops initalongside the existing identity setup prompt.Key changes
scripts/generate-schemas.mjs-- readsFilterConfig,ApiSubFilter,WorkspaceSubFilter, andOverrideConfigfromsrc/models/config.tsand generates both schema files. Runs as part ofprebuild/prelint/pretest.src/templates/copilot/configure-filter-prompt.mdand.ts-- prompt template for filter creationsrc/templates/copilot/configure-overrides-prompt.mdand.ts-- prompt template for override creation with token substitution guidancesrc/services/init-service.ts-- newgenerateCopilotConfigurationPrompts()method + conflict detection for the new filesdocs/commands/init.md,docs/guides/filtering-resources.md,docs/guides/environment-overrides.mdNotes
$schemacomment to work), but they are regenerated on every build from the canonical TypeScript types.extractor-config.schema.jsonfor consistency withconfiguration.extractor.yaml.$commentJSON Schema keyword carries the MIT license notice since JSON doesn't support traditional comments.